include/vsag/search_request.h:51

• Same indentation issue continues in the remainder of this bullet; keeping the alignment consistent avoids broken formatting in generated API docs.

      *            fewer neighbors than the returned Dim are padded with sentinel entries
      *            (id = -1, distance = +infinity). Batch KNN rejects an index containing external
      *            label -1 to keep this padding unambiguous.
     *          - Batched RANGE_SEARCH is not supported; implementations MUST reject
     *            NumElements > 1 for range mode.

include/vsag/index.h:340

• The new batch contract is only documented for SearchWithRequest, but HGraph and IVF's public KnnSearch overloads delegate here and now accept the same multi-query inputs. The overload documentation above still promises num_elements = 1 and a num_elements * k layout, so callers of the primary KNN APIs receive an incorrect contract; update those overloads too.

      *                - batched KNN requests, when supported by the implementation:
      *                  num_elements = query->GetNumElements(),
      *                  dim = implementation-defined returned row width. HGraph clamps it to
      *                  min(request.topk_, GetNumElements()), while IVF preserves
      *                  request.topk_. Callers MUST read `dim` from the returned dataset.
      *                  ids/distances are stored row-major with length (num_elements * dim).
      *                  Queries that yielded fewer than dim neighbors are padded with
       *                  sentinel entries (id = -1, distance = +infinity). Batch KNN rejects

src/algorithm/hgraph/hgraph_search.cpp:116

• This iterator-only single-query check is after the empty-index early return at line 92. IndexImpl deliberately forwards multi-query requests for the new batch handling, so a multi-query iterator call on an empty HGraph returns a single empty dataset instead of rejecting the unsupported iterator shape. Move the check before the early return.

    CHECK_ARGUMENT(query->GetNumElements() == 1,
                   "iterator-based KnnSearch only supports single query (NumElements=1)");

src/algorithm/hgraph/hgraph_search.cpp:936

• This RaBitQ rerank call also omits request.threshold_. As in the regular rerank branch, the post-rerank filter cannot recover eligible candidates discarded when the unfiltered top-k heap was formed, so thresholded batch KNN can return incomplete results. Pass the request threshold to reorder.

        } else if (mci_result.route != "mci" && !brute_force_used && search_param.enable_reorder &&
                   params.rabitq_one_bit_search) {
            this->reorder(raw_query, this->basic_flatten_codes_, search_result, k, nullptr, ctx);

src/algorithm/hgraph/hgraph_search.cpp:1026

• Unlike the single-query branch, which serializes mci_result.MakeStatistics(stats), the batch path always serializes only stats.Dump(). MCI-enabled batch searches therefore omit the mci_hybrid_*, seed-count, and raw-CSR diagnostics from the returned dataset, making the result statistics incomplete. Preserve or explicitly aggregate the per-query MCI metadata for batch results.

    if (query_count > 1) {
        dataset_results->Statistics(stats.Dump());
    }

src/algorithm/hgraph/hgraph_serialize.cpp:320

• The new active-padding rebuild is present for the modern label-info paths, but deserialize_basic_info_v0_14 still reads label_table_ directly at line 170 without rebuilding it. A legacy index containing an active external label -1 will therefore bypass the new batch-safety check and can return an ambiguous -1 result; rebuild the tracking set in that legacy path too.

        this->label_table_->RebuildActivePaddingLabelIds();

docs/docs/en/src/api/search.md:106

• This constraint is now inconsistent with the IVF implementation: batch KNN accepts one bucket list per query and validates the outer vector against the query count. Document the batch form here; otherwise callers will be told to use a shape that the new implementation deliberately supports.

- Currently only single-query is supported; the outer vector must contain exactly one entry.

docs/docs/zh/src/api/search.md:100

• 此约束已与 IVF 实现不一致：批量 KNN 支持每个查询一个桶列表，并会校验外层向量与查询数一致。这里应记录批量形式，否则文档会要求调用方使用新实现不支持的形状。

- 当前仅支持单查询；外层向量必须恰好包含一个条目。

src/algorithm/hgraph/hgraph_search.cpp:857

• Routing uses this separate ep_search_param, but it never receives base_search_param.time_cost; the searcher only checks InnerSearchParam::time_cost when enforcing timeout_ms. Consequently hierarchical routing in this batch path is not timeout-bounded. Propagate the request timer to the routing parameter (and reset it at the start of each query if the timeout is intended to be per-query).

    InnerSearchParam ep_search_param;
    ep_search_param.ep = this->entry_point_id_;
    ep_search_param.topk = 1;
    ep_search_param.ef = 1;
    ep_search_param.is_inner_id_allowed = nullptr;

src/algorithm/ivf/ivf.cpp:2145

• This batch branch invokes this->SearchWithRequest once per query, and each invocation creates a separate SearchStatistics; the outer stats object used for the final dataset is never updated. The returned batch result therefore reports zero distance evaluations and misses subquery timeouts even though the searches ran. Aggregate the subrequest statistics or refactor the batch path to share the query context.

        CHECK_ARGUMENT(request.expected_labels_.empty(),
                       "IVF batch search does not support expected labels");
        CHECK_ARGUMENT(request.topk_ > 0, "topk must be greater than 0");
        CHECK_ARGUMENT(!this->label_table_->HasActivePaddingLabel(),
                       "batch KNN does not support an index containing external label -1");

include/vsag/index.h:337

• This new batched-result contract is also reached by the non-iterator Index::KnnSearch overloads for HGraph and IVF (the added tests call those overloads with multi-element queries), but the public overload documentation above still states num_elements == 1. Update the direct KNN overload descriptions too, otherwise callers of the newly supported API are given the opposite shape contract.

      *                - batched KNN requests, when supported by the implementation:
      *                  num_elements = query->GetNumElements(),
      *                  dim = implementation-defined returned row width. HGraph clamps it to
      *                  min(request.topk_, GetNumElements()), while IVF preserves
      *                  request.topk_. Callers MUST read `dim` from the returned dataset.

src/algorithm/hgraph/hgraph_search.cpp:123

• Because the empty-index return above precedes this new validation, an iterator call with a multi-query dataset on an empty HGraph returns a successful empty dataset instead of rejecting the unsupported batch shape. This makes the single-query-only iterator contract depend on whether the index has data; validate NumElements() before the empty-index fast path.

    // Iterator state is maintained per query, so this overload remains single-query only.
    CHECK_ARGUMENT(query->GetNumElements() == 1,
                   "iterator-based KnnSearch only supports single query (NumElements=1)");

src/impl/label_table/label_table.cpp:188

• new_label == -1 is registered as an active padding label without checking whether source id i is removed. If a source index contains external label -1 and that vector was MARK_REMOVEd, merging it still makes the destination report an active padding label, causing all subsequent batch KNN requests to be rejected (and the source deletion state is not otherwise transferred). Carry the source keep/removal state through the merge and only register retained active labels.

            if (new_label == -1) {
                std::scoped_lock wlock(delete_ids_mutex_);
                active_padding_label_ids_.insert(new_inner_id);

docs/docs/en/src/api/search.md:37

• This description says range search only accepts one query, but the IVF disable_bucket_scan routing-only mode intentionally accepts batched requests (including the RANGE_SEARCH mode) and returns bucket IDs. Clarify the exception here so this user-facing documentation does not contradict the added regression test.

| `query_` | `DatasetPtr` | `nullptr` | The query. HGraph and IVF support contiguous multi-query KNN batches; range search supports one query only. |

docs/docs/zh/src/api/search.md:37

• 此处说明范围搜索只能接受一个查询，但 IVF 的 disable_bucket_scan 仅路由模式会有意接受批量请求（包括 RANGE_SEARCH 模式）并返回 bucket ID。请在这里说明该例外，避免用户文档与新增回归测试的行为不一致。

| `query_` | `DatasetPtr` | `nullptr` | 查询。HGraph 和 IVF 的 KNN 支持连续的多查询批次；范围搜索只支持单个查询。 |

include/vsag/search_request.h:56

• The public contract says every batched RANGE_SEARCH must be rejected, but the IVF disable_bucket_scan routing-only path intentionally accepts batched range requests and the regression test relies on that behavior. Document this explicit exception (or reject it in the routing path) so the API contract matches the implementation.

     *          - Batched RANGE_SEARCH is not supported; implementations MUST reject
     *            NumElements > 1 for range mode.

src/algorithm/hgraph/hgraph_search.cpp:893

• Resetting the shared timer here gives every query a fresh timeout_ms budget, so a batch can run roughly query_count * timeout_ms; additionally, ep_search_param has no timer and its routing work is not timed. This also changes single-query behavior. Preserve one request-wide deadline and pass the timer to entry-point search instead of resetting it per query.

        if (search_param.time_cost != nullptr) {
            search_param.time_cost->Reset();
        }

src/algorithm/hgraph/hgraph_search.cpp:648

• This guard relies on HasActivePaddingLabel(), but the legacy deserialize_basic_info_v0_14() path still loads label_table_ directly without calling RebuildActivePaddingLabelIds() (unlike the modern paths). A v0.14 index containing an active external label -1 will therefore pass this check and make batch padding ambiguous. Rebuild the tracker after the legacy label vector is read before allowing batch KNN.

        CHECK_ARGUMENT(!this->label_table_->HasActivePaddingLabel(),
                       "batch KNN does not support an index containing external label -1");

src/algorithm/ivf/ivf.cpp:2193

• Each child call creates a separate SearchStatistics/QueryContext, but the batch path discards that data and later serializes the outer stats. Batched IVF results therefore report zero distance evaluations and is_timeout=false even when a child search timed out; aggregate child statistics before returning the batch result.

            auto one_result = this->SearchWithRequest(one_request);
            if (not one_result.has_value()) {
                throw VsagException(ErrorType::INTERNAL_ERROR,
                                    "IVF batch search failed for a single query");
            }

src/algorithm/ivf/ivf.cpp:2162

• These buffers are raw allocations and are not attached to a Dataset until after all per-query futures complete. If any nested search throws, or future.get() rethrows that failure, both ids and distances leak before the outer IndexImpl can return an error. Keep them under allocator-aware RAII (or attach ownership before starting the loop) so failed batch searches do not permanently consume query memory.

        auto* alloc = select_query_allocator(ctx.alloc, this->allocator_);
        auto* ids = static_cast<int64_t*>(alloc->Allocate(sizeof(int64_t) * total_slots));
        auto* distances = static_cast<float*>(alloc->Allocate(sizeof(float) * total_slots));

src/impl/label_table/label_table.h:454

• This newly allocated robin set is not included in GetMemoryUsage() (which only counts deleted_ids_ around label_table.h:264-267). Index memory accounting will therefore under-report every index's label-tracking storage when active padding labels are present. Add this set's storage to the same estimate used for deleted_ids_.

    UnorderedSet<InnerIdType> deleted_ids_;  // Record deleted ids.
    UnorderedSet<InnerIdType> active_padding_label_ids_;

docs/docs/en/src/api/search.md:106

• The IVF implementation now accepts one bucket list per query (bucket_ids_.size() == query_count), including batched requests covered by the new tests, but this constraint still says the outer vector must contain exactly one entry. This would lead clients to construct an invalid request for multi-query KNN; document one entry per query instead.

- Currently only single-query is supported; the outer vector must contain exactly one entry.

docs/docs/zh/src/api/search.md:100

• 实现现在允许 IVF 批量请求为每个查询提供一个 bucket 列表（bucket_ids_.size() == query_count），而新增测试也覆盖了这种情况，但这里仍然写成外层向量必须恰好包含一个条目。多查询调用方会据此构造出无效请求；请改为说明每个查询对应一个条目。

- 当前仅支持单查询；外层向量必须恰好包含一个条目。

include/vsag/search_request.h:50

• The new batch contract documents only SearchWithRequest, but the public HGraph::KnnSearch and IVF::KnnSearch overloads also delegate to this path and now accept multi-query datasets. The corresponding overload comments in include/vsag/index.h still state NumElements == 1, so update the public API documentation consistently (or explicitly exclude those overloads).

     *          - Batched KNN: Set NumElements to the number of queries, with vectors
     *            stored contiguously. Supported by HGraph::SearchWithRequest and
     *            IVF::SearchWithRequest; results are returned with NumElements =
     *            query_count and a row-major Dim determined by the implementation

include/vsag/search_request.h:55

• Both HGraph and IVF reject expected_labels_ for batched KNN, but this batch contract does not state that restriction. A caller following the documented batch behavior and enabling reasoning receives an invalid-argument error; document that expected-label reasoning (and custom-distance callbacks, which are also single-query-only here) requires a single query.

     *            (id = -1, distance = +infinity). Batch KNN rejects an index containing external
      *            label -1 to keep this padding unambiguous.
     *          - Batched RANGE_SEARCH is not supported; implementations MUST reject

src/algorithm/hgraph/hgraph_search.cpp:893

• base_search_param.time_cost starts before the routing loop, but resetting it here discards routing time for every request, including single-query requests. A timeout can therefore be exceeded during routing and still receive a fresh full timeout_ms budget for approximate search, changing the previous single-query deadline behavior. Start/reset the timer before each query's routing (or otherwise account for routing) while preserving the intended batch budget.

            search_param.time_cost->Reset();
        }

src/algorithm/hgraph/hgraph_serialize.cpp:320

• This rebuild only covers the footer-based deserialization paths. The legacy deserialize_basic_info_v0_14 path still reads label_table_ directly and never rebuilds active_padding_label_ids_; a v0.14 index containing a live external label -1 will therefore pass HasActivePaddingLabel() and batch KNN can emit an ambiguous -1 value. Rebuild the active-label set immediately after the legacy label-table read as well.

        this->label_table_->RebuildActivePaddingLabelIds();

src/algorithm/ivf/ivf.cpp:2189

• Each batched row is executed through a recursive SearchWithRequest, which creates a fresh local SearchStatistics; the outer stats object dumped at line 2219 is never updated. Consequently a successful batched IVF result reports zero distance evaluations and other counters, and does not expose per-query timeout state, even though the nested searches performed work. Aggregate the nested statistics into the batch context (or route each search through the outer QueryContext) before returning.

            auto one_result = this->SearchWithRequest(one_request);

src/impl/label_table/label_table.h:454

• The newly allocated active_padding_label_ids_ set is not included in LabelTable::GetMemoryUsage(), which currently accounts for deleted_ids_ but not this set's dynamic storage. Index memory is therefore underreported whenever active external -1 labels are present. Include this set's allocated footprint in the memory-usage calculation.

    UnorderedSet<InnerIdType> active_padding_label_ids_;

src/utils/timer.cpp:52

• Reset() is newly added and is relied on by batched HGraph timeout handling, but src/utils/timer_test.cpp only covers construction, Record(), SetThreshold(), and destructor recording. Add a regression test that verifies a timeout threshold is measured from the reset point; otherwise the per-query timeout behavior can regress without a failing test.

Timer::Reset() {

tests/test_hgraph.cpp:4355

• dim is the loop variable for the current fixture dimension, but this assignment mutates it for the remainder of the test_cases loop. Since the RaBitQ cases occur before pq and the other quantizers, those later cases run at 960 instead of the requested fixture dimension, silently losing coverage. Compute a separate effective dimension for the RaBitQ case and leave dim unchanged.

                if (HGraphTestIndex::IsRaBitQ(base_quantization_str) &&
                    dim < fixtures::RABITQ_MIN_RACALL_DIM) {
                    dim = fixtures::RABITQ_MIN_RACALL_DIM;

tests/test_hgraph.cpp:4438

• This second new test repeats the same loop-variable mutation: once a RaBitQ case raises dim to 960, subsequent quantization cases in this dimension iteration no longer use the fixture dimension. That makes the test pass while skipping intended parameter coverage. Use a separate effective dimension for the RaBitQ build and dataset.

                if (HGraphTestIndex::IsRaBitQ(base_quantization_str) &&
                    dim < fixtures::RABITQ_MIN_RACALL_DIM) {
                    dim = fixtures::RABITQ_MIN_RACALL_DIM;